home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / tcl / dist6.3 / doc / SetResult.man < prev    next >
Encoding:
Text File  |  1992-04-30  |  9.7 KB  |  339 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/SetResult.man,v 1.8 91/12/06 10:35:02 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '    # BS - start boxed text
  93. '    # ^y = starting y location
  94. '    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '    # VS - start vertical sidebar
  125. '    # ^Y = starting y location
  126. '    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '    # Special macro to handle page bottom:  finish off current
  148. '    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_SetResult tcl
  189. .BS
  190. .SH NAME
  191. Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tcl.h>\fR
  195. .sp
  196. .VS
  197. \fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
  198. .VE
  199. .sp
  200. \fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
  201. .sp
  202. .VS
  203. \fBTcl_AppendElement\fR(\fIinterp, string, noSep\fR)
  204. .sp
  205. \fBTcl_ResetResult\fR(\fIinterp\fR)
  206. .sp
  207. \fBTcl_FreeResult\fR(\fIinterp\fR)
  208. .VE
  209. .SH ARGUMENTS
  210. .AS Tcl_FreeProc freeProc
  211. .AP Tcl_Interp *interp out
  212. Interpreter whose result is to be modified.
  213. .AP char *string in
  214. String value to become result for \fIinterp\fR or to be
  215. appended to existing result.
  216. .AP Tcl_FreeProc freeProc in
  217. .VS
  218. Address of procedure to call to release storage at
  219. \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
  220. \fBTCL_VOLATILE\fR.
  221. .AP int noSep in
  222. If non-zero then don't output a space character before this element,
  223. even if the element isn't the first thing in the result string.
  224. .VE
  225. .BE
  226.  
  227. .SH DESCRIPTION
  228. .PP
  229. The procedures described here are utilities for setting the
  230. result/error string in a Tcl interpreter.
  231. .PP
  232. \fBTcl_SetResult\fR
  233. arranges for \fIstring\fR to be the return string for the current Tcl
  234. command in \fIinterp\fR, replacing any existing result.
  235. .VS
  236. If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
  237. refers to an area of static storage that is guaranteed not to be
  238. modified until at least the next call to \fBTcl_Eval\fR.
  239. If \fIfreeProc\fR
  240. is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
  241. to \fBmalloc()\fR and is now the property of the Tcl system.
  242. \fBTcl_SetResult\fR will arrange for the string's storage to be
  243. released by calling \fBfree()\fR when it is no longer needed.
  244. If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
  245. points to an area of memory that is likely to be overwritten when
  246. \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
  247. In this case \fBTcl_SetResult\fR will make a copy of the string in
  248. dynamically allocated storage and arrange for the copy to be the
  249. return string for the current Tcl command.
  250. .PP
  251. If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
  252. \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
  253. of a procedure that Tcl should call to free the string.
  254. This allows applications to use non-standard storage allocators.
  255. When Tcl no longer needs the storage for the string, it will
  256. call \fIfreeProc\fR.  \fIFreeProc\fR should have arguments and
  257. result that match the type \fBTcl_FreeProc\fR:
  258. .nf
  259. .RS
  260.  
  261. typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
  262.  
  263. .RE
  264. .fi
  265. When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
  266. the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
  267. .VE
  268. .PP
  269. If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
  270. and \fBTcl_SetResult\fR
  271. re-initializes \fIinterp\fR's result to point to the pre-allocated result
  272. area, with an empty string in the result area.
  273. .PP
  274. .VS
  275. If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
  276. result, \fBTcl_SetResult\fR does whatever is necessary to dispose
  277. of the old result (see the \fBTcl_Interp\fR manual entry for details
  278. on this).
  279. .VE
  280. .PP
  281. \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
  282. It takes each of its \fIstring\fR arguments and appends them in order
  283. to the current result associated with \fIinterp\fR.
  284. .VS
  285. If the result is in its initialized empty state (e.g. a command procedure
  286. was just invoked or \fBTcl_ResetResult\fR was just called),
  287. then \fBTcl_AppendResult\fR sets the result to the concatenation of
  288. its \fIstring\fR arguments.
  289. .VE
  290. \fBTcl_AppendResult\fR may be called repeatedly as additional pieces
  291. of the result are produced.
  292. \fBTcl_AppendResult\fR takes care of all the
  293. storage management issues associated with managing \fIinterp\fR's
  294. result, such as allocating a larger result area if necessary.
  295. Any number of \fIstring\fR arguments may be passed in a single
  296. call;  the last argument in the list must be a NULL pointer.
  297. .PP
  298. \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
  299. .VS
  300. that it allows results to be built up in pieces.
  301. However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
  302. argument and it appends that argument to the current result
  303. as a proper Tcl list element.
  304. \fBTcl_AppendElement\fR adds backslashes or braces if necessary
  305. to ensure that \fIinterp\fR's result can be parsed as a list and that
  306. \fIstring\fR will be extracted as a single element.
  307. Under normal conditions, \fBTcl_AppendElement\fR will add a space
  308. character to \fIinterp\fR's result just before adding the new
  309. list element, so that the list elements in the result are properly
  310. separated.
  311. However, if \fIinterp\fR's result is empty when \fBTcl_AppendElement\fR
  312. is called, or if the \fInoSep\fR argument is 1, then no space
  313. is added.
  314. .PP
  315. \fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
  316. freeing the memory associated with it if the current result was
  317. dynamically allocated.
  318. It leaves the result in its normal initialized state with
  319. \fIinterp->result\fR pointing to a static buffer containing
  320. \fBTCL_RESULT_SIZE\fR characters, of which the first character
  321. is zero.
  322. \fBTcl_ResetResult\fR also clears the error state managed by
  323. \fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
  324. .PP
  325. \fBTcl_FreeResult\fR is a macro that performs part of the work
  326. of \fBTcl_ResetResult\fR.
  327. It frees up the memory associated with \fIinterp\fR's result
  328. and sets \fIinterp->freeProc\fR to zero, but it doesn't
  329. change \fIinterp->result\fR or clear error state.
  330. \fBTcl_FreeResult\fR is most commonly used when a procedure
  331. is about to replace one result value with another.
  332. .VE
  333.  
  334. .SH "SEE ALSO"
  335. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  336.  
  337. .SH KEYWORDS
  338. append, command, element, list, result, return value, interpreter
  339.